/*
 * Copyright 2002-2015 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.springframework.beans.factory.config;

import org.springframework.lang.Nullable;

/**
 * 为共享同一个Bean实例定义的注册接口,也就是进行注册单例Bean的定义接口,如果要将获取Bean的形式统一化,
 * 可以和{@link org.springframework.beans.factory.BeanFactory}一块使用.
 * <p>
 * 接口本身主要定义了对单例Bean的获取和注册方法.
 * Interface that defines a registry for shared bean instances.
 * Can be implemented by {@link org.springframework.beans.factory.BeanFactory}
 * implementations in order to expose their singleton management facility
 * in a uniform manner.
 * <p>
 * <p>The {@link ConfigurableBeanFactory} interface extends this interface.
 *
 * @author Juergen Hoeller
 * @see ConfigurableBeanFactory
 * @see org.springframework.beans.factory.support.DefaultSingletonBeanRegistry
 * @see org.springframework.beans.factory.support.AbstractBeanFactory
 * @since 2.0
 */
public interface SingletonBeanRegistry {

	/**
	 * 将已有的对象以指定的名称注册到bean注册表内,给定的该对象应该已经完全初始化.
	 * 注册表不会执行任何初始化回调(特别是,不会调用InitializingBean的afterPropertiesSet方法).
	 * 同时给定的实例,也不会收到任何销毁回调,比如DisposableBean的destroy方法.
	 * 当在一个完整的BeanFactory中运行时:如果你想要让你的Bean接受初始化和销毁方法的话,应该是注册一个Bean定义,而不是使用现有的实例.
	 * 通常在注册表配置期间被调用,但是也可以被用于单例的运行时注册,因此,注册表应该同步单例访问,如果他支持BeanFactory的单例懒加载,
	 * 那他就必须做.
	 * <p>
	 * <p>
	 * Register the given existing object as singleton in the bean registry,
	 * under the given bean name.
	 * <p>The given instance is supposed to be fully initialized; the registry
	 * will not perform any initialization callbacks (in particular, it won't
	 * call InitializingBean's {@code afterPropertiesSet} method).
	 * The given instance will not receive any destruction callbacks
	 * (like DisposableBean's {@code destroy} method) either.
	 * <p>When running within a full BeanFactory: <b>Register a bean definition
	 * instead of an existing instance if your bean is supposed to receive
	 * initialization and/or destruction callbacks.</b>
	 * <p>Typically invoked during registry configuration, but can also be used
	 * for runtime registration of singletons. As a consequence, a registry
	 * implementation should synchronize singleton access; it will have to do
	 * this anyway if it supports a BeanFactory's lazy initialization of singletons.
	 *
	 * @param beanName        the name of the bean
	 * @param singletonObject the existing singleton object
	 * @see org.springframework.beans.factory.InitializingBean#afterPropertiesSet
	 * @see org.springframework.beans.factory.DisposableBean#destroy
	 * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#registerBeanDefinition
	 */
	void registerSingleton(String beanName, Object singletonObject);

	/**
	 * 返回已注册的指定名称的单例对象.只检查已经实例化的单例,没有实例化的单例不会返回一个对象.
	 * 这个方法最主要的目的就是访问手动注册的单例类,
	 * 也可以用来以原始的方式访问由已经创建的bean来定义的单例实例.
	 * 需要注意的是:这个查找方法不支持Factory的前缀或者别名,在获取单例实例之前,需要将其解析承标准的名称.
	 * <p>
	 * <p>
	 * Return the (raw) singleton object registered under the given name.
	 * <p>Only checks already instantiated singletons; does not return an Object
	 * for singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to access manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to access a singleton
	 * defined by a bean definition that already been created, in a raw fashion.
	 * <p><b>NOTE:</b> This lookup method is not aware of FactoryBean prefixes or aliases.
	 * You need to resolve the canonical bean name first before obtaining the singleton instance.
	 *
	 * @param beanName the name of the bean to look for
	 * @return the registered singleton object, or {@code null} if none found
	 * @see ConfigurableListableBeanFactory#getBeanDefinition
	 */
	@Nullable
	Object getSingleton(String beanName);

	/**
	 * 检查此注册表是否包含指定名称的单例实例.只检查已经实例化的单例,如果单例bean定义还没有被实例化,那么就不会返回true.
	 * 该方法的主要目的就是为了检查手动注册的bean,也可以用来检查通过一个已经实例化的bean定义的单例实例.
	 * 可以使用BeanFactory的containsBeanDefinition方法检查指定的bean名称对应的bean定义是否包含在bean工厂内.
	 * 也可以调用containsBeanDefinition或者containsSingleton来查看特定的工厂内是否包含了指定名称的bean.
	 * 通常是使用BeanFactory的containBean方法来检查工厂是否了解指定的bean名称(是否是手动注册的或者通过其他bean定义来创建的bean),
	 * 同样也会向它的祖先工厂检查查询.
	 * 需要注意的是:
	 * 这个查找方法是不知吃bean工厂前缀或者别名的,所以需要在检查单例状态之前,转换成标准的bean名称.
	 * <p>
	 * <p>
	 * Check if this registry contains a singleton instance with the given name.
	 * <p>Only checks already instantiated singletons; does not return {@code true}
	 * for singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to check manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to check whether a
	 * singleton defined by a bean definition has already been created.
	 * <p>To check whether a bean factory contains a bean definition with a given name,
	 * use ListableBeanFactory's {@code containsBeanDefinition}. Calling both
	 * {@code containsBeanDefinition} and {@code containsSingleton} answers
	 * whether a specific bean factory contains a local bean instance with the given name.
	 * <p>Use BeanFactory's {@code containsBean} for general checks whether the
	 * factory knows about a bean with a given name (whether manually registered singleton
	 * instance or created by bean definition), also checking ancestor factories.
	 * <p><b>NOTE:</b> This lookup method is not aware of FactoryBean prefixes or aliases.
	 * You need to resolve the canonical bean name first before checking the singleton status.
	 *
	 * @param beanName the name of the bean to look for
	 * @return if this bean factory contains a singleton instance with the given name
	 * @see #registerSingleton
	 * @see org.springframework.beans.factory.ListableBeanFactory#containsBeanDefinition
	 * @see org.springframework.beans.factory.BeanFactory#containsBean
	 */
	boolean containsSingleton(String beanName);

	/**
	 * 返回已经注册的单例bean集合的名称集合.之间查已经实例化的单例,不会检查那些还没有实例化的单例类.
	 * 它的主要目的是检查通过手动注册的单例实例和通过已经注册的bean实例间接的创建的实例类.
	 * <p>
	 * <p>
	 * Return the names of singleton beans registered in this registry.
	 * <p>Only checks already instantiated singletons; does not return names
	 * for singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to check manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to check which singletons
	 * defined by a bean definition have already been created.
	 *
	 * @return the list of names as a String array (never {@code null})
	 * @see #registerSingleton
	 * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionNames
	 * @see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionNames
	 */
	String[] getSingletonNames();

	/**
	 * 返回已经注册的单例实例的数量,不考虑没有实例化的单例,主要目的是用来检查手动注册和通过已经实例化的bean间接创建的单例bean.
	 * Return the number of singleton beans registered in this registry.
	 * <p>Only checks already instantiated singletons; does not count
	 * singleton bean definitions which have not been instantiated yet.
	 * <p>The main purpose of this method is to check manually registered singletons
	 * (see {@link #registerSingleton}). Can also be used to count the number of
	 * singletons defined by a bean definition that have already been created.
	 *
	 * @return the number of singleton beans
	 * @see #registerSingleton
	 * @see org.springframework.beans.factory.support.BeanDefinitionRegistry#getBeanDefinitionCount
	 * @see org.springframework.beans.factory.ListableBeanFactory#getBeanDefinitionCount
	 */
	int getSingletonCount();

	/**
	 * 检测已经注册的单例是否互斥(在其他的注册渠道).
	 * Return the singleton mutex used by this registry (for external collaborators).
	 *
	 * @return the mutex object (never {@code null})
	 * @since 4.2
	 */
	Object getSingletonMutex();

}
